perm filename HELP.BH[UP,DOC]3 blob sn#128263 filedate 1974-11-07 generic text, type T, neo UTF8
The HELP program is intended to provide short, minimal documentation
for system programs and facilities.  For the most part, such help
is provided in the form of short text files which are typed by the
HELP program,, but the program is also capable of running other
programs and of executing monitor commands a la DO.

The command "HELP name" looks for a file on the [3,2] area with
filename NAME and an extension matching one of those listed below.
The first (should be only!) such file found in the UFD is processed
in accordance with its extension:

<null>	type as text
TXT	type as text
DMP	run via SWAP UUO
CMD	type into input buffer to be executed as commands
DPY	like CMD, but user must be at a DD or III
LNK	read ASCII name from file and use as new HELP argument

In reading ASCII files (all but DMP), TV/E directories and SOS line
numbers are ignored.  The user must be logged in to use a CMD or DPY
HELPer.  Also, since those typically have side effects like writing
files, each contains a warning message which is typed out before
the commands are executed; the user must confirm by typing Y that he
really wants the HELPer executed.  The format of a CMD or DPY helper
is <warning>⊗<commands>, e.g.:
	This HELPer produces a such-and-such listing on the XGP.
	Please type Y to confirm: ⊗XSPOOL SUCH-AND-SUCH
If the first character of the HELPer is ⊗, it is executed without
waiting for confirmation.

Note that DMP files can be executed not-logged-in; writers of DMP
files on [3,2] should bear that in mind when writing their programs.

In scanning a LNK file, letters and digits are accumulated up to a
non-alphameric or the sixth character.  The resulting name is then
treated as if it had been typed by the user.  Thus two HELP arguments
can refer to the same text file and there is only one copy to update
if the program being documented changes.

HELP files should mention filenames of other documentation when
available.  Remember that the user may not know the syntax of the
TYPE command, so instead of
	For more information: TYPE MUMBLE.FOO[UP,DOC].
you should use an unambiguous notation like
	For more information, type "TYPE MUMBLE.FOO[UP,DOC]".
(Remember also that the user may be at an uppercase-only, standard ASCII
terminal!)  If you write a DMP file with effects other than typing something
on the user's terminal, it is a good idea for your program to ask for
confirmation first.

A PRUNE.DAT file exists for [3,2]; also, PRUNE has been modified so that
for [3,2] only it sorts the file by filename first rather than extension
first.  Writers of HELPers should add descriptions to the PRUNE.DAT file.
(The command "HELP HELPER" types the filename and use fields only of the
PRUNE.DAT file.)

If there is no HELP file on the topic specified by the user, the HELP
program looks for files with that name and any extension on [UP,DOC],
[S,DOC], and [AIM,DOC] in that order.  The full name of the first such
file found, if any, is typed, with a suggestion that the user might
want to read that file.  The file itself is not typed out, on the
theory that users of HELP are looking for short help rather than full
documentation.  Thus, if you can think of nothing to say about your
program other than the location of the full documentation, you need
not bother.  For utility programs, though, you can usually think of
some short and sweet paragraph which will get the user through the
most common uses of your program.

[xxx,DOC] files with extension UPD are not listed as described in the
previous paragraph, except that if both NAME.EXT and NAME.UPD are found
on the same PPN, both are mentioned.